🗣 Description

Configuration file parameters can now be overridden selectively from the command line. This allows re-use of config files. This is invoked with the -ConfigFilePath option and supplying other command line options

💭 Motivation and context

Currently if a configuration file is re-used and any changes are needed, an entire config file needs to be re-defined.
This will reduce the maintenance of config files.

Related to this, issue #345 poor defaults has been resolved by the current config module implementation

This change was implemented by 3 changes to the Orchestrator code

1. All of the command line options in the ReportGroup have been added to the Configuration group so they are visible when using of a config file.

2. The ConfigFilePath is added as a mandatory option in the Configuration group which triggers that group. Otherwise the Report Group is triggered.

3. If the Configuration group is active, the following additional processing is performed

• The code expects authentication parameters ( if present ) to reside in $PSBoundParameters ( values passed in from the command line ). Therefore if an authentication is set in the config file and not present in the bound parameters already copy the value to the bound parameters. This allows any command line value to override the configuration file value
• Next any $PSBound parameter that is present other that ConfigFilePath is copied to the $PSBoundParameters. Then if a respective $PSBoundParameter is set the option has either been passed on the command line or was an authentication related parameter, so update the config parameter used in the rest of the processing.

4. ScubaConfig supports defaults, but two defects were resolved ( OPAPath and OutRegoFileName so it will now handle a config file with no parameters other than the description

The resolution of this issue should also resolve and close issue #345, which is no or poor defaults, since the ScubaConfig module code now provides these.

TODO: Parameter value defaults now have a duplicate definition in Invoke-SCuBA and ScubaConfig. This
has been filed as issue #767

TODO: Documentation is being updated as issue #344

🧪 Testing

The original submission was done with a manual testing process. Since that time I have developed a Pester test as a new module in the Orchestrator unit tests. There is already a unit test for the config tests and since these changes affect the orchestrator it was more appropriate to add them here. The Manual test is documented at the end of this section

Pester Test
A new pester test InvokeScubsConfigTests.ps1 has been added. The test invokes Invoke-SCuBA as follows ( using a hash for the arguments ).

Invoke-SCuBA  -M365Environment gcc -ConfigFilePath < full path to orchestrator_config_test.yaml file>

The orchestrator_config_test.yaml. file specifies the M365environment as commercial, but the command line overrides this to gcc. The resulting configuration ( apart from ConfigFIlePath ) is stored in the Configuration value of the ScubaConfig singleton class. The value is cloned to a separate instances, the ScubaConfig module is reloaded from the config file and the two values are compared.

For orchestrator_config_test.yaml has dummy authentication parameters in it ( no real values in this commit ).

Comparison is done invoking the newly written PsTestUtils.psm1 Compare-Hashes function. which returns true if the two configuration hash table instances compare .

On the first test, the compare should fail, indicating that the configuration was indeed modified and overwritten by the command line value

The second test is run like the first except the the reference hash table is read from the config file and the the M365Environment value is modifies to match the command line value. The compare as run now should pass

Manual testing process:
Prior to the development of the pester test above the following manual test was done.

1). Run
Invoke-SCuba -ConfigFilePath config_test.yaml
with following settings in config_test.yaml
( Authentication parameters are masked in the example below )

Description: YAML Configuration file for unit test in SCuBA

ProductNames:
- teams
M365Environment: commercial
OPAPath: .
LogIn: true
DisconnectOnExit: false
OutPath: .
OutFolderName: M365BaselineConformance
OutProviderFileName: ProviderSettingsExport
OutRegoFileName: TestResults
OutReportName: BaselineReports
Organization:  XXXX
AppID: XXXX
CertificateThumbprint: XXXX

2. Run with overrrides ( example command shown )
   Invoke-SCuba -ProductNames aad -ConfigFilePath config_test.yaml

3. Rerun with authentication parameter overrides

4. Run with degenerate config file ( description only ) to verify defaults operation

✅ Pre-approval checklist

• This PR has an informative and human-readable title.
• Changes are limited to a single goal - eschew scope creep!
• All future TODOs are captured in issues, which are referenced
  in code comments.
• All relevant type-of-change labels have been added.
• I have read the CONTRIBUTING document.
• These code changes follow cisagov code standards.
• All relevant repo and/or project documentation has been updated
  to reflect the changes in this PR. Document Support for Config Files #344
• Tests have been added and/or modified to cover the changes in this PR.
• All new and existing tests pass.

✅ Pre-merge checklist

• Revert dependencies to default branches.
• Finalize version.

✅ Post-merge checklist

• Create a release.